<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title></title>
  </head>
    <body>
        <h1>SQLite database access API</h1>
        
        <p>
            Most new devices contain one version of sqlite or another; sqlite is a very lightweight SQL database 
            designed for embedding into devices. For portability we recommend avoiding SQL altogether since 
            it is both fragmented between devices (different sqlite versions) and isn't supported on all devices.
        </p>

        <p>In general SQL seems overly complex for most embedded device programming tasks.</p>

        <h3>Portability Of SQLite</h3>
        <p>SQLite is supported on iOS, Android, UWP (Universal Windows Platform), RIM, Desktop &amp; JavaScript builds. However, the JavaScript 
            version of SQL has been deprecated and isn't supported on all platforms.</p>
        <p>You will notice that at this time support is still missing from the Windows builds.</p>
        <p>The biggest issue with SQLite portability is in iOS. The SQLite version for most platforms is 
            threadsafe and as a result very stable. However, the iOS version is not!</p>
        <p>This might not seem like a big deal normally, however if you forget to close a connection the GC might 
            close it for you thus producing a crash. This is such a common occurrence that Codename One logs 
            a warning when the GC collects a database resource on the simulator.</p>

        <h3>Using SQLite</h3>
        <p>SQL is pretty powerful and very well suited for common tabular data. The Codename One SQL 
            API is similar in spirit to JDBC but considerably simpler since many of the abstractions of JDBC 
            designed for pluggable database architecture make no sense for a local database.</p>

        <p>The {@link com.codename1.db.Database} API is a high level abstraction that allows you to open an 
            arbitrary database file using syntax such as:</p>

        <script src="https://gist.github.com/codenameone/184eb4b7303878dc4688.js"></script>
        
        <p>Some SQLite apps ship with a "ready made" database. We allow you to replace the DB file by using the code:</p>

        <script src="https://gist.github.com/codenameone/b1140f9c3abb44d53276.js"></script>

        <p>You can then use the {@link com.codename1.io.FileSystemStorage} class to write the content of your 
            DB file into the path. Notice that it must be a valid SQLite file!</p>

        <p>This is very useful for applications that need to synchronize with a central server or applications that 
            ship with a large database as part of their core product.</p>

        <p>Working with a database is pretty trivial, the application logic below can send arbitrary queries to the 
            database and present the results in a {@link com.codename1.ui.table.Table}. You can probably integrate 
            this code into your app as a debugging tool:</p>

        <script src="https://gist.github.com/codenameone/282b02c20e7bd067f1f0.js"></script>
        
        <img src="https://www.codenameone.com/img/developer-guide/sql-table.png" alt="Querying the temp demo generated by the SQLDemo application">
        <img src="https://www.codenameone.com/img/developer-guide/sql-entry.png" alt="Issuing a query">
        
        
    </body>
</html>
